This document contains information about ODF's linking support.
Table of Contents
-------------------------
• Introduction
• Linking Update
• Content Object Changes
• Selection Object Notes
• Fixed Linking Problems
• Framework Changes
• Sample Code Changes
• Known Linking Problems
• Framework Problems
• Sample Code Problems
Introduction
The current release represents a continuing effort to identify and correct problems in ODF's linking support. Many bugs, both serious and small, have been addressed.
The existing architecture is incomplete, in that it does not provide a full implementation for linking as described in the OpenDoc human interface guidelines. However, future versions of ODF will address this problem. In the meantime, the current linking code provides a solid foundation for linking. In particular, the linking related responsibilities of non-linking parts are now handled much more effectively by the framework.
This document explains the update to ODF's linking code and explains what you need to do in your part to support linking.
Linking Update
The following sections discuss the changes to ODF code since Release 2, and the implications these changes will have on your parts.
Content Object Changes
It is no longer necessary to test for kODPropContentFrame in the NewPromise method of a part's main content object. Due to changes in FW_CPart::CloneInto, the call to NewPromise is only made when appropriate.
See the "Known OpenDoc Problems" document in the Release Notes folder for a description of a problem that may affect your implementation of NewPromise in the content objects representing your part and your link sources.
Selection Object Notes
All embedding parts (regardless of whether they support linking) should override FW_CSelection::CanPasteAsLink. The FW_MPasteAsHandler calls this method to determine the correct setting for the Merge and Embed radio buttons in the Paste As dialog. This setting is determined by checking for the presence or absence of 1) the kODPropContentFrame property and 2) a value of a kind that can be merged into the kODPropContents property in the provided storage unit.
If no mergeable value exists, then the setting should be kODPasteAsEmbedOnly. Otherwise, it should be kODPasteAsEmbed when kODPropContent frame is present, and kODPasteAsMerge when absent.
Linking parts which do not embed need not override CanPasteAsLink, as long as the fAllowLink member of FW_CSelection is accurate. FW_CSelection::CanPasteAsLink will return fAllowLink, and provide a setting of kODPasteAsMergeOnly, the only setting appropriate for a non-embedding part.
Fixed Linking Problems
The following sections describe the linking problems that have been fixed for this release.
Framework Changes
• As of ODF R2, FW_CPart::CloneInto determines the storage kind that is being used for a cloning operation. The part's dirty flag is not cleared as the result of a cloning operation that was triggered by drag and drop or the clipboard. This fix makes it possible to use promises when your part's content is being cloned. (An OpenDoc bug prevents the use of promises when writing out content to a link storage unit in this circumstance. See "Known OpenDoc Problems" in the Release Notes folder for details.)
• FW_CDragCommand::DoIt now calls IsOKtoEdit when fDragResult is kODDropMove. If the part is embedded in a link destination, or if the drag directly modifies link destination content, this will trigger an appropriate dialog. If IsOKtoEdit returns false (user did not choose to break the link in the dialog), then the move is undone, and the transaction aborted, leaving both the drag source and drop target in the same state they began. (Exception: a copy of content dragged to the trash or control-dragged to a non-OpenDoc document will remain in the trash or the document. Only an OpenDoc part can respond to the aborting of the transaction.)
Sample Code Changes
• ODFDraw now handles resolution of clipboard promises correctly when a promised shape is removed from the part's content (this is not linking-specific).
• ODFDraw now allows the creation of multiple link destinations from the same link source by consecutive Paste-As from the same clipboard.
• ODFDraw now allows the creation of multiple link destinations from the same source, such as when performing a Copy and Paste As operation of an existing link source multiple times, or command-dragging an existing link source.
Known Linking Problems
The following sections list the known problems with linking in both the ODF framework code and the ODF sample code.
Framework Problems
• The current linking design does not support transferring links from a subset of the part's content via the clipboard and drag and drop. This behavior will be added to a future release of ODF.
• The FW_CLinkDestination::LinkUpdated method currently calls the DoPropagateChanges method, which in turn calls the FW_CPresentation::ContentUpdated method. If multiple link destinations share the same ODLink object, DoPropagateChanges should not be called until all of the link destinations have been updated. Theoretically, the problem is that they may have different presentations (frames).
• FW_CODPart and FW_CLinkDestination::LinkUpdated don't handle an initial update failure appropriately. This error occurs when the ODLink::GetContentStorageUnit method throws an exception with the error value kODErrCannotEstablishLink. When this exception is thrown, ODF should remove the link from the part and abort the pending undo transaction.
This error condition occurs after the creation of a cross-document link when the part fails to create a link source. Although this is a relatively unlikely occurrence, it needs to be handled. OpenDoc's embedding support provides unlimited opportunity for interacting with 'unknown quantities'.
Sample Code Problems
• ODFDraw never enables the Link Info menu item.
• ODFDraw and ODFTable do not transfer links via the clipboard or drag and drop.
• ODFDraw does not allow the user to select and copy portions of a link destination.
• ODFDraw and ODFTable do not display link borders.
• ODFDraw does not allow overlapping link sources. ODFDraw also does not allow a link source to contain a link destination directly. A source or destination can be contained in a part embedded in a link source.
• ODFDraw and ODFTable don't handle frame removal correctly in certain cases, when running under OpenDoc 1.1.2 or earlier versions. For example:
1. Make changes to a link source which includes at least one embedded frame (destination updates);
2. cut and paste content including the updated destination;
3. undo the paste, undo the cut;
4. undo the change at the source (destination updates);
5. redo the change at the source (destination updates);
6. redo the cut, redo the paste.
This will cause a kODErrInvalidFrame exception to be thrown, and other side effects, possibly including crashing. The problem is that the update in step 4 causes the proxy to be deleted, and triggers a call to ODFrame::Removed. But when the paste is redone in step 5, the part that did the paste tries to reinstate the very same frame!
The solution, which will be implemented in the next release of ODF, is for the cut command (or clear or drag) to acquire a reference to the linked proxy, thus protecting it from being deleted until OpenDoc commits the undo stack. At that point, ODFrame::Removed will only be called if the frame is in limbo (i.e. is not in use anywhere). Since the entire Undo stack is committed at the same time, there's no chance that any attempt to continue using that frame will be made.
This problem won't exist with OpenDoc 1.2, because the frame being pasted in that case is not the same frame as the one that was cut.
• ODFDraw and ODFTable don't handle content of a broken link properly.
1. Make changes to a link source (destination updates);
2. break a link destination (in ODFDraw, this can be done by attempting to edit destination content, and using the "Break Link" button in the dialog);
3. make changes to the former destination content;
4. undo the changes; undo breaking the link;
5. undo the source change (link updates);
6. redo the source change (link updates);
7. redo breaking the link;
8. redo the changes.
The update in step 5 caused the previous destination content to be removed from the part, but the same objects are being treated as part of the part content when the final change is redone in step 8. The change, which now should apply to the new linked content, is actually applied to the old linked content, which is not visible anymore.
The solution, which will be implemented in the next release of ODF and the samples, is: when redoing breaking the link, swap the original content back into the part and the link, and delete the updated content. The nature of undo/redo guarantees that these objects will match in appearance. At the point that the link updated in step 6, there was no way to recognize that a complementary undo and redo had occurred, but when breaking the link is redone, it is recognized that any updates that did occur, must have been in complementary pairs, so one can in a sense 'Undo' the updates after the fact.
• ODFDraw writes promises when updating a link source containing intrinsic content. Due to a bug in OpenDoc, any destination updates resulting from dropping content from outside OpenDoc into an embedded frame which is part of a link source within ODFDraw will fail. The destination(s) will resynchronize with the source on the next update.
For a link consisting of a single embedded frame, there's no way to prevent the embedded part from causing a fatal problem by promising in its CloneInto implementation under the same circumstances. ODFDraw, the only ODF example part that normally promises in CloneInto, avoids this case by returning NULL from CDrawPartContent::NewPromise when the storage kind is FW_kLinkStorage.
